home *** CD-ROM | disk | FTP | other *** search
/ IRIX Base Documentation 2002 November / SGI IRIX Base Documentation 2002 November.iso / usr / share / catman / p_man / cat3 / libpod.z / libpod
Encoding:
Text File  |  2002-10-03  |  10.2 KB  |  199 lines
  1.  
  2.  
  3.  
  4. LLLLIIIIBBBBPPPPOOOODDDD((((3333))))                        IIIImmmmpppprrrreeeessssssssaaaarrrriiiioooo                         LLLLIIIIBBBBPPPPOOOODDDD((((3333))))
  5.  
  6.  
  7.  
  8. LLLLIIIIBBBBRRRRAAAARRRRYYYY DDDDEEEESSSSCCCCRRRRIIIIPPPPTTTTIIIIOOOONNNN
  9.      _l_i_b_p_o_d provides a C language application programming interface (API) to
  10.      the Printer Object Database (POD). The _l_i_b_p_o_d library provides printer
  11.      driver developers with an API to create and maintain a POD and provides
  12.      application developers with the means to acquire detailed information
  13.      about a printer. A POD contains information on the current configuration,
  14.      state and job history of a single printer. Each printer physically
  15.      installed on a system maintains its own POD. All interaction with a
  16.      printer's POD should be done through _l_i_b_p_o_d. Direct modification of the
  17.      POD files is strongly discouraged. For detailed information on the
  18.      creation and format of the POD files refer to the _p_o_d(_4) man page.
  19.  
  20. PPPPOOOODDDD FFFFIIIILLLLEEEESSSS
  21.      A Printer Object Database consists of three separate ASCII text files.
  22.      The name of each POD file is formed from the printer name and the suffix
  23.      ._c_o_n_f_i_g, ._s_t_a_t_u_s and ._l_o_g, respectively.  The information contained in
  24.      each file is summarized below.
  25.  
  26.      [[[[pppprrrriiiinnnntttteeeerrrr nnnnaaaammmmeeee]]]]....ccccoooonnnnffffiiiigggg
  27.                     This file contains detailed information on the printer's
  28.                     capabilities.  Examples include the possible paper sizes,
  29.                     printer location and available fonts. Initially, this file
  30.                     is created by the printer driver developer and a copy is
  31.                     installed when the printer is added to the system. The
  32.                     contents of this file are typically maintained by the
  33.                     system administrator and are not normally changed.
  34.  
  35.      [[[[pppprrrriiiinnnntttteeeerrrr nnnnaaaammmmeeee]]]]....ssssttttaaaattttuuuussss
  36.                     This file contains information about the current
  37.                     operational status of the printer. The information in the
  38.                     file indicates whether the printer is busy, what type of
  39.                     printing media is installed, and so on. The contents of
  40.                     this file change during every print job.
  41.  
  42.      [[[[pppprrrriiiinnnntttteeeerrrr nnnnaaaammmmeeee]]]]....lllloooogggg
  43.                     This file contains the print job history for the printer,
  44.                     information for old as well as current print jobs.
  45.  
  46.      The default location for POD files is /_v_a_r/_s_p_o_o_l/_l_p/_p_o_d. The global
  47.      variable _P_D_p_o_d__p_a_t_h indicates the location of the POD files and is set to
  48.      the default path by _l_i_b_p_o_d. Note that _P_D_p_o_d__p_a_t_h is set to
  49.      /_u_s_r/_s_p_o_o_l/_l_p/_p_o_d which is linked to /_v_a_r/_s_p_o_o_l/_l_p/_p_o_d. This is for
  50.      compatilibty with printer hosts running older versions of the IRIX
  51.      operating system. If POD files are to be located in a directory other
  52.      than the default, _P_D_p_o_d__p_a_t_h should be set to the pathname of the new
  53.      location. _P_D_p_o_d__p_a_t_h is declared in the header file _p_o_d._h. Note that the
  54.      maximum string length for _P_D_p_o_d__p_a_t_h is PPPPDDDD____SSSSTTTTRRRR____MMMMAAAAXXXX. This includes the
  55.      terminating NULL character.
  56.  
  57.  
  58.  
  59.  
  60.  
  61.  
  62.  
  63.                                                                         PPPPaaaaggggeeee 1111
  64.  
  65.  
  66.  
  67.  
  68.  
  69.  
  70. LLLLIIIIBBBBPPPPOOOODDDD((((3333))))                        IIIImmmmpppprrrreeeessssssssaaaarrrriiiioooo                         LLLLIIIIBBBBPPPPOOOODDDD((((3333))))
  71.  
  72.  
  73.  
  74. FUNCTIONS
  75.      Many _l_i_b_p_o_d functions come in two forms, a standard form and a local
  76.      form.  The POD files reside only on the system to which the printer is
  77.      physically connected, referred to as the printer host. Therefore, to
  78.      provide information about a printer located on another system, _l_i_b_p_o_d
  79.      must be able to communicate across the network. The standard form of the
  80.      _l_i_b_p_o_d functions (i.e. functions whose names do not contain the word
  81.      "local") automatically determine whether the specified printer is located
  82.      on the user's system (a local printer), or whether the printer is on a
  83.      remote system (a remote printer). After determining where the printer is
  84.      located, the standard functions access the POD files on the appropriate
  85.      system. Since network communication carries a certain amount of
  86.      performance overhead, _l_i_b_p_o_d provides the local functions (i.e. the names
  87.      with the word "local"). These functions are provided for use by programs
  88.      that are guaranteed to be run on the printer host machine. A printer
  89.      driver is an example of such a program.  Typically, user application
  90.      programs such as printer status tools use the standard form of the _l_i_b_p_o_d
  91.      functions, since it is likely that these programs will need to work with
  92.      remote printers.
  93.  
  94.      Note that the functions that write to POD files (e.g. _P_D_L_o_c_a_l_W_r_i_t_e_L_o_g)
  95.      are available only in local form. Since only printer drivers should have
  96.      a need to write to the POD files, there is no need to provide for writing
  97.      to the files from anywhere except from the system to which the printer is
  98.      physically connected.
  99.  
  100.      DDDDeeeettttaaaaiiiilllleeeedddd IIIInnnnffffoooorrrrmmmmaaaattttiiiioooonnnn MMMMaaaannnniiiippppuuuullllaaaattttiiiioooonnnn
  101.                PDReadInfo        PDLocalReadInfo
  102.                                  PDLocalWriteInfo
  103.  
  104.      SSSSttttaaaattttuuuussss FFFFiiiilllleeee MMMMaaaannnniiiippppuuuullllaaaattttiiiioooonnnn
  105.                PDReadStatus      PDLocalReadStatus
  106.                                  PDLocalWriteStatus
  107.                PDReadOpStatus    PDLocalReadOpStatus
  108.  
  109.      LLLLoooogggg FFFFiiiilllleeee MMMMaaaannnniiiippppuuuullllaaaattttiiiioooonnnn
  110.                PDReadLog         PDLocalReadLog
  111.                                  PDLocalWriteLog
  112.  
  113.      CCCCoooonnnnvvvveeeennnniiiieeeennnncccceeee FFFFuuuunnnnccccttttiiiioooonnnnssss
  114.                PDMakeMessage
  115.                PDFindPageSize
  116.                PDGetCurrentResolution
  117.                PDGetSizeCodeByName
  118.                PDGetNameBySizeCode
  119.  
  120.      EEEExxxxeeeeccccuuuuttttiiiioooonnnn EEEErrrrrrrroooorrrr HHHHaaaannnnddddlllliiiinnnngggg
  121.                PDPerror
  122.  
  123.  
  124.  
  125.  
  126.  
  127.  
  128.  
  129.                                                                         PPPPaaaaggggeeee 2222
  130.  
  131.  
  132.  
  133.  
  134.  
  135.  
  136. LLLLIIIIBBBBPPPPOOOODDDD((((3333))))                        IIIImmmmpppprrrreeeessssssssaaaarrrriiiioooo                         LLLLIIIIBBBBPPPPOOOODDDD((((3333))))
  137.  
  138.  
  139.  
  140. LIBRARY ACCESS
  141.      Programs that call _l_i_b_p_o_d functions must include the _p_o_d._h header file
  142.      located in the /_u_s_r/_i_n_c_l_u_d_e directory. In addition, the programs must
  143.      link with the _l_i_b_p_o_d._a library located in /_u_s_r/_l_i_b. Programs that use the
  144.      standard functions must also link with _l_i_b_s_p_o_o_l._a. Programs that use only
  145.      the local functions need not link with this additional library. The link
  146.      lines for each case would be:
  147.  
  148.      When using standard functions:    ... -lpod -lspool ...
  149.      When using only local functions:  ... -lpod ...
  150.  
  151. NNNNEEEETTTTWWWWOOOORRRRKKKK CCCCOOOOMMMMMMMMUUUUNNNNIIIICCCCAAAATTTTIIIIOOOONNNN
  152.      To provide remote printer POD information, _l_i_b_p_o_d communicates over the
  153.      network with the _p_o_d_d(_1_M) daemon on the remote machine. Since the network
  154.      or remote machine may be down when a _l_i_b_p_o_d function is executed, a
  155.      timeout may occur and the function will return the appropriate error
  156.      code. The timeout period can be specified by setting the global variable
  157.      PPPPDDDDnnnneeeetttt____ttttiiiimmmmeeeeoooouuuutttt to a value in seconds. The default timeout period is shown
  158.      in the header file _p_o_d._h. While a large timeout period is appropriate
  159.      when reading printer status, a much smaller timeout may be appropriate
  160.      for browsing printer configurations.
  161.  
  162.      For more information on the daemon refer to the _p_o_d_d(_1_M) man page.
  163.  
  164. DDDDEEEEBBBBUUUUGGGGGGGGIIIINNNNGGGG
  165.      If the global variable _P_D_d_e_b_u_g is set to a non-zero value, _l_i_b_p_o_d will
  166.      print debugging information to standard error during execution.  _P_D_d_e_b_u_g
  167.      is declared in the header file _p_o_d._h.
  168.  
  169. WWWWAAAARRRRNNNNIIIINNNNGGGG
  170.      The standard form of the _l_i_b_p_o_d functions call the _l_i_b_s_p_o_o_l function
  171.      _S_L_G_e_t_P_r_i_n_t_e_r_I_n_f_o. This _l_i_b_s_p_o_o_l function is not reentrant. This means
  172.      that any pointer returned by a previous call to _S_L_G_e_t_P_r_i_n_t_e_r_I_n_f_o will be
  173.      invalid after a call to the standard form of the _l_i_b_p_o_d functions.
  174.  
  175. SSSSEEEEEEEE AAAALLLLSSSSOOOO
  176.      pod(4), libspool(3), podd(1M)
  177.  
  178.  
  179.  
  180.  
  181.  
  182.  
  183.  
  184.  
  185.  
  186.  
  187.  
  188.  
  189.  
  190.  
  191.  
  192.  
  193.  
  194.  
  195.                                                                         PPPPaaaaggggeeee 3333
  196.  
  197.  
  198.  
  199.